<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Choosing a Replication Manager acknowledgement policy</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_replicate.html" title="Running replication using the db_replicate utility" />
    <link rel="next" href="rep_elect.html" title="Elections" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Choosing a Replication Manager acknowledgement policy</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_replicate.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_elect.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_mgr_ack"></a>Choosing a Replication Manager acknowledgement policy</h2>
          </div>
        </div>
      </div>
      <p>
        Replication Manager allows the user to choose from a variety
        of acknowledgement policies. There are two characteristics
        that should be considered when choosing the policy:
        consistency and durability. Consistency means making sure some
        number of clients have applied all available master
        transactions. Durability, in this context, means only
        indicating success only if enough clients have applied a
        transaction. The issue of how many is enough depends on the
        application's requirements and varies per acknowledgement
        policy. For example, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> means the data
        will survive a change in master or a network partition. In
        most cases, the number of sites for consistency is equal to
        the number of sites for durability. Replication Manager uses
        the consistency value to decide whether or not to wait for
        acknowledgements. Replication manager uses the durability
        value to decide either the transaction was successfully
        processed or that a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event should be
        generated.
    </p>
      <p>
        Replication Manager also strives to give the application the
        answer and return to the application as quickly as possible.
        Therefore, if it knows that the number of sites connected is
        insufficient to meet the consistency value, then it does not
        wait for any acknowledgements and if it knows that the
        durability value cannot be met, it returns
        <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> immediately to the user.
    </p>
      <p>
        With one exception, discussed below, all acknowledgement
        policies combine the consistency and durability values. For
        most policies the primary purpose is the durability of the
        data. For example, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> policy ensures
        that, if successful, the transaction's data is safe in the
        event of a network partition so that a majority of the sites
        in the group have the data. The <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_NONE" class="olink">DB_REPMGR_ACKS_NONE</a> policy
        does not consider either consistency or durability, and it is
        very fast because it does not wait for any acknowledgements
        and it does not ever trigger the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>
        event. Other policies, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a> and
        <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>, have a primary purpose of
        consistency. These two policies wait for acknowledgements from
        all (or all electable) sites in the group.
    </p>
      <p>
        In the face of failure, however, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a>
        and <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a> policies can result in a
        surprising lack of consistency due to the fact that
        Replication Manager strives to give the answer back to the
        application as fast as it can. So, for example, with
        <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a>, and one site down, Replication Manager
        knows that disconnected site can never acknowledge, so it
        immediately triggers <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>. An
        unfortunate side effect of this policy is that existing,
        running sites may fall further and further behind the master
        if the master site is sending a fast, busy stream of
        transactions and never waiting for any site to send an
        acknowledgement. The master does not wait because the
        consistency value cannot be met, and it does trigger the
        <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event because the durability value
        cannot be met, but those actions now affect the consistency of
        the other running sites.
    </p>
      <p>
        In order to counteract this unfortunate side effect, the
        <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_AVAILABLE" class="olink">DB_REPMGR_ACKS_ALL_AVAILABLE</a> acknowledgement policy focuses
        on the consistency aspect, but also considers durability. This
        policy uses all sites for consistency, and a quorum of sites
        for its decision about durability. As long as there is a
        non-zero number of client replicas to send to, the master will
        wait for all available sites to acknowledge the transaction.
        As long as any client site is connected, this policy will
        prevent the master from racing ahead if one or more sites is
        down. On the master, this policy will then consider the
        transaction durable if the number of acknowledgements meets
        quorum for the group.
    </p>
      <p>
        The following acknowledgement policies determine durability
        using acknowledgements from electable peers only:
        <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a>, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ONE_PEER" class="olink">DB_REPMGR_ACKS_ONE_PEER</a>,
        <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>. An electable peer is a site where
        the priority value is greater than zero. In replication groups
        using these policies, an unelectable site does not send
        acknowledgements and cannot contribute to transaction
        durability.
    </p>
      <p>
        If your application needs to associate a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>
        event with the specific transaction and thread that caused it,
        this can be done by using your platform's thread-specific data
        facility. You can create a thread-specific data structure that
        contains a durability indicator. You would set the durability
        indicator in the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> portion of your event
        notification callback function. You can then check and clear the
        durability indicator after your transaction commit operation
        completes. You must be careful to coordinate this approach across
        all application threads performing transaction commits or checkpoints
        because any of these threads can generate a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>
        event. The ex_rep_mgr sample application demonstrates one way to
        implement this capability. See
        <a class="xref" href="rep_ex.html" title="Ex_rep: a replication example">Ex_rep: a replication example</a> for more information.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_replicate.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_elect.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Running replication using the
        db_replicate utility </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Elections</td>
        </tr>
      </table>
    </div>
  </body>
</html>
